OneSpan Sign Developer: Conditional Fields – Part 3

In the previous two blogs in this series, we outlined the basics of Conditional Fields in Part 1, and then we clarified the syntax of the conditions demonstrated how to leverage the feature through REST API in Part 2.

Next this ongoing blog series will show how to create Conditional Fields using the SDK and explain how to build a package with conditions and retrieve the referenced logics afterwards. Let’s get started!

Create Conditional Fields via SDK

OneSpan Sign offers a neat and clean solution to specify the conditions during the package creation to minimize the outbound API numbers. The sample Java code below demonstrates how it’s implemented:

        FieldCondition condition = FieldConditionBuilder.newFieldCondition()
				.withId("ConditionId")
				.withCondition("document['DocumentId'].field['fieldId2'].value == 'X'")
				.withAction("document['DocumentId'].field['fieldId1'].disabled = false")
				.build();
        DocumentPackage pkg = PackageBuilder.newPackageNamed("Test Conditional Fields")
                .describedAs("Description")
                .withSigner(SignerBuilder.newSignerWithEmail("[email protected]")
                        .withFirstName("Patty")
                        .withLastName("Galant"))
                .withDocument(DocumentBuilder.newDocumentWithName("Document")
                        .withId("DocumentId")
                        .fromFile("path_to_your_document")
                        .withSignature(SignatureBuilder.signatureFor("[email protected]")
                                .withId(new SignatureId("signatureId"))
                                .onPage(0)
                                .atPosition(400, 100)
                                .withField(FieldBuilder.textField()
                                        .withId(new FieldId("fieldId1"))
                                        .onPage(0)
                                        .atPosition(0, 0))
                                .withField(FieldBuilder.checkBox()
                                        .withId(new FieldId("fieldId2"))
                                        .onPage(0)
                                        .atPosition(0, 0))))
                .withCondition(condition)
                .build();

        PackageId pkgId = eslClient.createPackageOneStep(superDuperPackage);

Find more examples for Java and .NET.

Retrieve Referenced Logics

Once a package is created with conditional logics, OneSpan Sign provides integrators the ability to quickly retrieve the list of conditions defined for a specific document or field. This allows developers to easily manage the specified conditions. 

For API Integrators

HTTP Request

GET /api/packages/{packageId}/referencedConditions?documentId={documentId}&fieldId={fieldId}

HTTP Headers

Accept: application/json 
Authorization: Basic api_key 

The two parameters “documentId” and “fieldId” are optional, which can be used to filter the returned entities.

Note: 

• Specifying field ID without document ID will return an error.
• The presence of the parameters won’t affect the response schema, as shown below.

Response Payload

{
  "packageId": "-2l-waYVRfeK3gD0ZsJCiOhr6TI=",
  "documents": [
    {
      "documentId": "6e6295d1925dd910e4c71a43842ee0434b3e88e0f7b0f2d6",
      "fields": [
        {
          "fieldId": "GXqapEOZlQIL",
          "conditions": {
            "referencedInCondition": [
              {
                "id": "ddcf978d-37e8-4d63-9016-c771d32ef96a",
                "condition": "document['6e6295d1925dd910e4c71a43842ee0434b3e88e0f7b0f2d6'].field['GXqapEOZlQIL'].value == 'X'",
                "action": "document['6e6295d1925dd910e4c71a43842ee0434b3e88e0f7b0f2d6'].field['cbvt5zkgLNw3'].required = true"
              }
            ],
            "referencedInAction": []
          }
        },
        {
          "fieldId": "cbvt5zkgLNw3",
          "conditions": {
            "referencedInCondition": [],
            "referencedInAction": [
              {
                "id": "ddcf978d-37e8-4d63-9016-c771d32ef96a",
                "condition": "document['6e6295d1925dd910e4c71a43842ee0434b3e88e0f7b0f2d6'].field['GXqapEOZlQIL'].value == 'X'",
                "action": "document['6e6295d1925dd910e4c71a43842ee0434b3e88e0f7b0f2d6'].field['cbvt5zkgLNw3'].required = true"
              }
            ]
          }
        }
      ]
    }
  ]
}

All conditions where the current field is involved either in the “condition” or “action” expressions will be listed at “documents” array > “fields” array > “conditions” array > “referencedInCondition” or “referencedInAction” arrays. Therefore, it’s expected that one conditional logic appears in all relevant field nodes. 

For SDK Integrators

Similarly, our SDKs expose the corresponding functions to retrieve the referenced conditions per package, document, or field. In the “PackageService” class, three functions have been introduced. Let’s check the method signatures:

Note: 

• Make sure your SDK version is 11.28 or later. 
• “ReferencedConditions” object is modelled based on the JSON schema from API response.

This should give you some insight into developing this feature with the SDK. OneSpan plans to continue developing the Conditional Fields feature to bring even more value in future versions. Check back to the OneSpan blog for the latest information on enhancements or behavior changes.

If you have any questions regarding this blog or anything else concerning integrating OneSpan Sign into your application, visit the Developer Community Forums. Your feedback matters to us!

OneSpan Developer Community

Join the OneSpan Developer Community! Forums, blogs, documentation, SDK downloads, and more.

Join Today